feat: Add configuration provider interface #184

pontemonti · 2026-02-04T20:15:34Z

This pull request introduces a hierarchical, provider-based configuration pattern throughout the Agents365 SDK, deprecating direct environment variable access and legacy utility functions. It adds new configuration classes and providers for runtime, tooling, and observability settings, and applies these patterns to both documentation and code. The changes also introduce OpenAI-specific observability configuration scaffolding, update linting rules to enforce the new configuration approach, and refactor token caching to use the new provider model.

Configuration System Overhaul

Introduced the configuration provider pattern across the SDK, with new classes: RuntimeConfiguration, ToolingConfiguration, and ObservabilityConfiguration, each with default singleton providers (e.g., defaultRuntimeConfigurationProvider). This enables hierarchical, function-based overrides for multi-tenant support and deprecates direct use of environment utilities. [1] [2] [3] [4]
Updated documentation to reflect the new configuration system, replacing function-based environment utilities with configuration properties and showing usage patterns for both default and custom providers. [1] [2] [3]

OpenAI Observability Extension

Added OpenAIObservabilityConfiguration and associated options/types, following the provider pattern for future extensibility and type safety. Exported a singleton provider (defaultOpenAIObservabilityConfigurationProvider) for this configuration. [1] [2] [3] [4]
Declared a dependency on @microsoft/agents-a365-runtime in the OpenAI observability extension package.

Agentic Token Cache Refactor

Refactored AgenticTokenCache to accept an IConfigurationProvider<ObservabilityConfiguration>, defaulting to defaultObservabilityConfigurationProvider, enabling per-tenant configuration and improved testability. Exported both the class and a default singleton instance. [1] [2] [3] [4] [5]

Linting and Code Quality

Updated ESLint configuration to enforce the use of configuration classes instead of direct process.env access and to disallow deprecated API usage, with exceptions for configuration, test, and utility files. [1] [2]

Documentation and Environment Variables

Expanded documentation of environment variables to include new observability settings and clarified their relationship to the new configuration classes. [1] [2]

These changes collectively modernize the SDK’s configuration approach, improve extensibility and testability, and lay the groundwork for multi-tenant and advanced observability scenarios.

Resolved conflicts: - observability/src/index.ts: Combined ILogger exports with configuration exports - observability/src/utils/logging.ts: Merged setLogger/getLogger/resetLogger pattern with configuration provider support for DefaultLogger - tooling/src/McpToolServerConfigurationService.ts: Combined imports for IConfigurationProvider with Authorization and AgenticAuthenticationService - tooling/src/Utility.ts: Combined imports for IConfigurationProvider with ChannelAccount Updated tests to match merged implementation: - Removed createLogger factory tests (replaced by setLogger/getLogger/resetLogger) - Updated GetAgenticUserToken expectations to include scopes parameter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The scopes parameter was added as required in main branch, which is a breaking change for existing consumers. This adds overloads to maintain backward compatibility: - 3-param signature (deprecated): Uses default MCP platform scope - 4-param signature: Explicit scopes for better control Existing code calling GetAgenticUserToken(auth, handler, ctx) will continue to work, but callers are encouraged to migrate to the explicit scopes overload for clarity. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…vider Added detailed JSDoc explaining: - The provider creates a single cached configuration instance - Default module-level providers are singletons - Two approaches for multi-tenant scenarios: 1. Dynamic override functions reading from async context (recommended) 2. Per-tenant provider instances when needed This clarifies that while the singleton pattern is used, multi-tenancy is still supported through function-based overrides that resolve at runtime. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Added documentation to AgenticTokenCacheInstance explaining it uses default configuration and when to create custom instances - Exported AgenticTokenCache class so consumers can create instances with custom IConfigurationProvider for multi-tenant scenarios - Added class-level documentation with usage example Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…guration

…onment utility functions

…guration

…onfigurations for LangChain and OpenAI

…figuration

…riable handling

… utility imports and updating server listing logic

…ode.

Copilot

Pull request overview

This pull request introduces a comprehensive hierarchical configuration provider pattern throughout the Agents365 SDK, replacing direct process.env access with configuration classes that support programmatic overrides and multi-tenant scenarios. The PR adds new configuration classes (RuntimeConfiguration, ToolingConfiguration, ObservabilityConfiguration) with default singleton providers, applies these patterns across runtime, tooling, and observability packages, and introduces extensive test coverage.

Changes:

Introduces configuration provider pattern with base RuntimeConfiguration class and package-specific extensions
Adds comprehensive test coverage for all configuration classes and related functionality
Deprecates direct environment variable access and legacy utility functions
Updates ESLint rules to enforce configuration usage and prevent deprecated API usage

Reviewed changes

Copilot reviewed 70 out of 71 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`packages/agents-a365-runtime/src/configuration/*`	New configuration infrastructure with interfaces, base classes, and default providers
`packages/agents-a365-runtime/src/power-platform-api-discovery.ts`	Converts `ClusterCategory` from type alias to enum for better type safety
`packages/agents-a365-runtime/src/environment-utils.ts`	Deprecates utility functions and delegates to configuration classes where possible
`packages/agents-a365-runtime/src/agentic-authorization-service.ts`	Adds overload accepting explicit scopes parameter
`packages/agents-a365-tooling/src/configuration/*`	Tooling configuration extending runtime configuration
`packages/agents-a365-tooling/src/Utility.ts`	Deprecates URL construction methods in favor of service usage
`packages/agents-a365-tooling/src/McpToolServerConfigurationService.ts`	Refactored to use configuration provider
`packages/agents-a365-observability/src/configuration/*`	Observability configuration extending runtime configuration
`packages/agents-a365-observability/src/utils/logging.ts`	Updated to use configuration provider for dynamic log level resolution
`packages/agents-a365-observability/src/tracing/*`	Multiple tracing utilities updated to use configuration
`packages/agents-a365-observability-hosting/src/caching/AgenticTokenCache.ts`	Refactored to accept configuration provider
`packages/agents-a365--extensions-/src/configuration/*`	Extension-specific configurations for OpenAI, LangChain, Claude tooling and observability
`tests/*/.test.ts`	Comprehensive test coverage for all new configuration classes
`eslint.config.mjs`	New rules to enforce configuration usage and prevent deprecated API usage
`docs/*.md`	Documentation updates reflecting the new configuration pattern

fpfp100 · 2026-02-06T18:11:00Z

CHANGELOG.md is not updated.

…ationImprovements # Conflicts: # pnpm-lock.yaml

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts

…ub.com/microsoft/Agent365-nodejs into users/johanb/ConfigurationImprovements

…ants Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 70 out of 71 changed files in this pull request and generated 11 comments.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

packages/agents-a365-runtime/src/environment-utils.ts

packages/agents-a365-tooling/src/Utility.ts

packages/agents-a365-observability/src/configuration/ObservabilityConfigurationOptions.ts

docs/design.md

CLAUDE.md

packages/agents-a365-runtime/src/environment-utils.ts

packages/agents-a365-tooling/src/configuration/ToolingConfiguration.ts

packages/agents-a365-runtime/src/configuration/RuntimeConfigurationOptions.ts

packages/agents-a365-runtime/docs/design.md

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts

- Introduced PerRequestSpanProcessorConfiguration to encapsulate per-request export settings. - Removed per-request related properties from ObservabilityConfiguration. - Updated documentation to reflect changes in configuration structure. - Adjusted tests to validate new configuration class and removed obsolete tests. - Ensured backward compatibility by maintaining environment variable handling for per-request settings.

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts

* feat: Add x-ms-agentid header (#183) Co-authored-by: Johan Broberg <johanb@microsoft.com> * set gen_ai.caller.agent.type (#187) Co-authored-by: jsl517 <pefan@microsoft.com> * fix: update @isaacs/brace-expansion to version 5.0.1 (#181) Co-authored-by: Johan Broberg <johanb@microsoft.com> * feat: Add configuration provider interface (#184) * Add PRD for configuration provider for Agent 365 SDK * Change to dynamic resolution for configuration settings * feat: Add configuration provider interface * Update lock file * fix: add backward-compatible overloads to GetAgenticUserToken The scopes parameter was added as required in main branch, which is a breaking change for existing consumers. This adds overloads to maintain backward compatibility: - 3-param signature (deprecated): Uses default MCP platform scope - 4-param signature: Explicit scopes for better control Existing code calling GetAgenticUserToken(auth, handler, ctx) will continue to work, but callers are encouraged to migrate to the explicit scopes overload for clarity. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: clarify multi-tenant usage patterns for DefaultConfigurationProvider Added detailed JSDoc explaining: - The provider creates a single cached configuration instance - Default module-level providers are singletons - Two approaches for multi-tenant scenarios: 1. Dynamic override functions reading from async context (recommended) 2. Per-tenant provider instances when needed This clarifies that while the singleton pattern is used, multi-tenancy is still supported through function-based overrides that resolve at runtime. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: clarify AgenticTokenCache singleton usage and export class - Added documentation to AgenticTokenCacheInstance explaining it uses default configuration and when to create custom instances - Exported AgenticTokenCache class so consumers can create instances with custom IConfigurationProvider for multi-tenant scenarios - Added class-level documentation with usage example Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * add utility methods for parsing environment variables in RuntimeConfiguration * add setLogger and resetLogger tests * docs: enhance JSDoc comments for RuntimeConfigurationOptions * docs: update deprecation notices and provide usage examples for environment utility functions * refactor: update McpToolRegistrationService to use ClaudeToolingConfiguration * refactor: update McpToolRegistrationService to use specific tooling configurations for LangChain and OpenAI * refactor: ensure undefined checks for tooling overrides in ToolingConfiguration * refactor: enhance ObservabilityConfiguration tests for environment variable handling * refactor: streamline McpToolRegistrationService by removing redundant utility imports and updating server listing logic * Address review feedback and discrepancies between documentation and code. * Address additional feedback; add missing tests, improve documentation * fix: add guardrails comment for PerRequestSpanProcessor default constants Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Johan Broberg <johanb@microsoft.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> * Initial plan * Fix test: Add event method to custom logger mocks --------- Co-authored-by: Johan Broberg <johan@pontemonti.net> Co-authored-by: Johan Broberg <johanb@microsoft.com> Co-authored-by: PengF <126631706+fpfp100@users.noreply.github.com> Co-authored-by: jsl517 <pefan@microsoft.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

* clean up * support event logs and add events for export. * Fix test failure after adding event method to ILogger interface (#186) * Initial plan * Fix test failure by adding event method to ILogger mocks - Updated all mock ILogger objects in custom-logger.test.ts to include the event method - Updated setLogger validation to check for event method - Updated error message to include event method in validation Co-authored-by: fpfp100 <126631706+fpfp100@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: fpfp100 <126631706+fpfp100@users.noreply.github.com> * comments * comments * comments * comment * doc update * Resolve merge conflicts with main branch (#188) * feat: Add x-ms-agentid header (#183) Co-authored-by: Johan Broberg <johanb@microsoft.com> * set gen_ai.caller.agent.type (#187) Co-authored-by: jsl517 <pefan@microsoft.com> * fix: update @isaacs/brace-expansion to version 5.0.1 (#181) Co-authored-by: Johan Broberg <johanb@microsoft.com> * feat: Add configuration provider interface (#184) * Add PRD for configuration provider for Agent 365 SDK * Change to dynamic resolution for configuration settings * feat: Add configuration provider interface * Update lock file * fix: add backward-compatible overloads to GetAgenticUserToken The scopes parameter was added as required in main branch, which is a breaking change for existing consumers. This adds overloads to maintain backward compatibility: - 3-param signature (deprecated): Uses default MCP platform scope - 4-param signature: Explicit scopes for better control Existing code calling GetAgenticUserToken(auth, handler, ctx) will continue to work, but callers are encouraged to migrate to the explicit scopes overload for clarity. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: clarify multi-tenant usage patterns for DefaultConfigurationProvider Added detailed JSDoc explaining: - The provider creates a single cached configuration instance - Default module-level providers are singletons - Two approaches for multi-tenant scenarios: 1. Dynamic override functions reading from async context (recommended) 2. Per-tenant provider instances when needed This clarifies that while the singleton pattern is used, multi-tenancy is still supported through function-based overrides that resolve at runtime. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: clarify AgenticTokenCache singleton usage and export class - Added documentation to AgenticTokenCacheInstance explaining it uses default configuration and when to create custom instances - Exported AgenticTokenCache class so consumers can create instances with custom IConfigurationProvider for multi-tenant scenarios - Added class-level documentation with usage example Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * add utility methods for parsing environment variables in RuntimeConfiguration * add setLogger and resetLogger tests * docs: enhance JSDoc comments for RuntimeConfigurationOptions * docs: update deprecation notices and provide usage examples for environment utility functions * refactor: update McpToolRegistrationService to use ClaudeToolingConfiguration * refactor: update McpToolRegistrationService to use specific tooling configurations for LangChain and OpenAI * refactor: ensure undefined checks for tooling overrides in ToolingConfiguration * refactor: enhance ObservabilityConfiguration tests for environment variable handling * refactor: streamline McpToolRegistrationService by removing redundant utility imports and updating server listing logic * Address review feedback and discrepancies between documentation and code. * Address additional feedback; add missing tests, improve documentation * fix: add guardrails comment for PerRequestSpanProcessor default constants Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Johan Broberg <johanb@microsoft.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> * Initial plan * Fix test: Add event method to custom logger mocks --------- Co-authored-by: Johan Broberg <johan@pontemonti.net> Co-authored-by: Johan Broberg <johanb@microsoft.com> Co-authored-by: PengF <126631706+fpfp100@users.noreply.github.com> Co-authored-by: jsl517 <pefan@microsoft.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --------- Co-authored-by: jsl517 <pefan@microsoft.com> Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: Johan Broberg <johan@pontemonti.net> Co-authored-by: Johan Broberg <johanb@microsoft.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Johan Broberg and others added 18 commits February 3, 2026 10:02

Add PRD for configuration provider for Agent 365 SDK

f5a6625

Change to dynamic resolution for configuration settings

2fa7ab0

feat: Add configuration provider interface

47f109c

Update lock file

65507a0

add utility methods for parsing environment variables in RuntimeConfi…

0a141f7

…guration

add setLogger and resetLogger tests

461bf77

docs: enhance JSDoc comments for RuntimeConfigurationOptions

5484e0f

docs: update deprecation notices and provide usage examples for envir…

2fd9b3b

…onment utility functions

refactor: update McpToolRegistrationService to use ClaudeToolingConfi…

ccc09c3

…guration

refactor: update McpToolRegistrationService to use specific tooling c…

ae18d5a

…onfigurations for LangChain and OpenAI

refactor: ensure undefined checks for tooling overrides in ToolingCon…

328f414

…figuration

refactor: enhance ObservabilityConfiguration tests for environment va…

eb92810

…riable handling

refactor: streamline McpToolRegistrationService by removing redundant…

bda6efd

… utility imports and updating server listing logic

Address review feedback and discrepancies between documentation and c…

7ea4b12

…ode.

pontemonti marked this pull request as ready for review February 5, 2026 06:36

pontemonti requested review from a team as code owners February 5, 2026 06:36

pontemonti requested review from Copilot, rahuldevikar761 and tmlsousa February 5, 2026 06:36

Copilot started reviewing on behalf of pontemonti February 5, 2026 06:36 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

Address additional feedback; add missing tests, improve documentation

0a9a6ec

tmlsousa previously approved these changes Feb 5, 2026

View reviewed changes

Merge branch 'main' into users/johanb/ConfigurationImprovements

62f9ea6

juliomenendez previously approved these changes Feb 6, 2026

View reviewed changes

nikhilNava previously approved these changes Feb 6, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into users/johanb/Configur…

02cb9bb

…ationImprovements # Conflicts: # pnpm-lock.yaml

fpfp100 reviewed Feb 6, 2026

View reviewed changes

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts Show resolved Hide resolved

Merge branch 'users/johanb/ConfigurationImprovements' of https://gith…

e983d40

…ub.com/microsoft/Agent365-nodejs into users/johanb/ConfigurationImprovements

pontemonti dismissed stale reviews from nikhilNava, juliomenendez, and tmlsousa via e983d40 February 6, 2026 18:45

fix: add guardrails comment for PerRequestSpanProcessor default const…

c9d6c8f

…ants Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings February 6, 2026 18:58

Copilot started reviewing on behalf of pontemonti February 6, 2026 18:59 View session

fpfp100 previously approved these changes Feb 6, 2026

View reviewed changes

pontemonti enabled auto-merge (squash) February 6, 2026 19:00

Copilot AI reviewed Feb 6, 2026

View reviewed changes

fpfp100 reviewed Feb 6, 2026

View reviewed changes

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts Show resolved Hide resolved

fix: correct documentation

3efcbd4

tmlsousa approved these changes Feb 6, 2026

View reviewed changes

tmlsousa previously approved these changes Feb 6, 2026

View reviewed changes

Johan Broberg added 2 commits February 6, 2026 11:59

Address PR feedback

f4bbbde

pontemonti dismissed stale reviews from tmlsousa and fpfp100 via f4bbbde February 6, 2026 22:16

fpfp100 approved these changes Feb 6, 2026

View reviewed changes

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts Show resolved Hide resolved

packages/agents-a365-observability/src/configuration/ObservabilityConfiguration.ts Show resolved Hide resolved

tmlsousa approved these changes Feb 6, 2026

View reviewed changes

juliomenendez approved these changes Feb 7, 2026

View reviewed changes

pontemonti merged commit 26700e2 into main Feb 7, 2026
7 checks passed

pontemonti deleted the users/johanb/ConfigurationImprovements branch February 7, 2026 00:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add configuration provider interface #184

feat: Add configuration provider interface #184

Uh oh!

pontemonti commented Feb 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

fpfp100 commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

feat: Add configuration provider interface #184

feat: Add configuration provider interface #184

Uh oh!

Conversation

pontemonti commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

fpfp100 commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pontemonti commented Feb 4, 2026 •

edited

Loading